什麼是 API? RESTful API 該怎麼理解? (12)

2024-05-12 01:59| 来源: 网络整理| 查看: 265

在這系列的前幾篇文章著重在個體，探討了網頁端是怎麼由 HTML 組成以及透過 CSS 長成什麼樣子，這篇文章會來介紹前後端溝通的重要觀念 API。

什麼是 API

API (Application Programming Interface)，中文是應用程式介面，介面是用於程式間溝通的抽象概念。

溝通，重要的是訊息的交換

以男女交往來說重要的溝通是

丟球: 會不會丟球，不會丟球對方就不知道該怎麼和你進一步互動接球: 對方丟球該怎麼接到，該怎麼看到球飛過來

人與人之間的情感，就是透過傳接球這個介面來慢慢讓感情升溫的，搞不清楚介面，會憑實力單身。

API 介面在前後端之間扮演的角色就是提供請求和回覆的格式和規範，在設計 API 的時候，對 API 而言重要的是

傳入: 收到什麼樣子的參數傳出: 回傳什麼樣子的結果

當我們完整的定義了 "傳入" 和 "傳出" 參數的樣子後，也就完成了 API 的設計。

前後端之間溝通重要的傳入和傳出是

Request: 前端向後端請求資料 Response: 後端回覆前端的請求什麼是 Request

Request 是瀏覽器向後端取得資料的方式，一個 Request 通常包含以下參數

URL: 要跟後端的哪個路徑互動 method: HTTP method headers: Client Request 的相關資訊 body: 資料類型且需要傳輸的內容大多會存放在此 credntial: 像是同源政策類的設定什麼是 Response

Response 則是定義了瀏覽器可以取得的資料格式，一個 Response 通常包含以下參數

headers: Server Response 的相關資訊 body: 資料類型且需要傳輸的內容大多會存放在此 status: 回應請求的狀態 statusText: 狀態相關的訊息什麼是 RESTful API

REST (Representational State Transfer) 是一種依照資源來設計 API 界面的一種架構，透過架構來定義 API 的傳入和傳出該如何去組成和設計，通常 RESTful API 會是在講基於 HTTP 通訊協定上的介面服務設計。

資源指的是任何可以讓用戶端存取的物件、資料、服務

資源必須具有識別碼 (ID) 也就是 URI 來讓用戶進行存取，接著會透過 REST 這種交換資源的表示法來與資源互動。

舉女孩子喜歡吃的美食當例子

傳入: /users/ariel/favorite-food-list/ 傳出: 甜點店清單、火鍋店清單、早午餐店清單

RESTful API 會使用標準的 HTTP method 當作動詞來對資源進行操作

GET: 取得資料 POST: 新增資料 PUT: 修改資料 DELETE: 刪除資料

依照 RESTful API 來設計 API 的 URI 應該避免把動詞放在 URI 中 /create-favorite-food-list/ 較好的方式會是 /favorite-food-list/ + POST。

一般來說 URI 中的資源都會是複數名詞，並且透過階層來描述資源之間的關係:

/users/ariel: 代表取得 ariel 這個使用者的相關資訊 /users/ariel/favorite-food-list/: 代表 ariel 的美食清單

不過一般建議階層最多就是兩層即可，避免造成設計上的複雜以及使用彈性的下降。

在對資源操作過後，在傳出時也有幾個常用的狀態碼

200: 成功 201: 已建立 204: 沒有內容 400: 無效的請求 404: 找不到 409: 衝突，通常會用在 PUT 失敗 OpenAPI Specification

OpenAPI Specification 是一種機器可讀介面文件的規範，用來描述、生成、使用和視覺化 RESTful Web 服務。

常聽到的產品會是 Swagger，以前 OpenAPI 是 Swagger 框架的一部分，在 2016 年後成為一個獨立項目，受到 Linux 基金會的一個開源協作項目 OpenAPI Initiative 監督。

Swagger

Swagger 是 REST API 的工具，可以自動建立清晰明瞭的 REST API 文件，在開發流程上幫助設計、構建、記錄和使用 REST API。

推薦大家可以直接使用線上的編輯器去體驗，傳送門在此:

https://editor.swagger.io/

原則上就是透過編輯 yaml 檔來定義 API 的傳入和傳出，貼上最基本範例，定義了 book 相關的 API 和參數內容。

swagger: "2.0" info: description: "API 文件" version: "1.0.0" title: "Swagger Book Store" host: "swagger.io" basePath: "/v1" schemes: - "https" - "http" paths: /api/v1/book/{bookId}: get: tags: - "Book" summary: "Find Book by ID" description: "For valid response try integer IDs with value >= 1" operationId: "getBookById" produces: - "application/json" parameters: - name: "bookId" in: "path" description: "ID of pet that needs to be fetched" required: true type: "integer" maximum: 10.0 minimum: 1.0 format: "int64" responses: "200": description: "successful operation" schema: $ref: "#/definitions/Book" "400": description: "Invalid ID supplied" "404": description: "Order not found" definitions: Book: type: "object" properties: id: type: "integer" format: "int64" JS Doc

如果不使用 REST 的規範又想要額外撰寫相關的傳入和傳出，Node 的後端通常會需要透過 JSDoc 註解產生 API 文件。

/** * Represents a book. * @constructor * @param {string} title - The title of the book. * @param {string} author - The author of the book. */ function Book(title, author) {}

只要下指令安裝 npm install jsdoc，然後就可以直接 jsdoc yourJavaScriptFile.js 在短短幾秒內自動生成出網頁版的 API 文件。

不過檔案內容當然要搭配上特殊的註解 /** 開頭，這樣才可以被 JSDoc 辨識出來。

【本文地址】

公司简介

联系我们